home *** CD-ROM | disk | FTP | other *** search
/ Acorn Risc Technologies StrongARM CD-ROM / Acorn Risc Technologies StrongARM CD-ROM.iso / ftp / documents / appnotes / 290_305 / 293c / Text < prev   
Encoding:
Text File  |  1996-01-31  |  10.8 KB  |  320 lines
  1. -----------------------------------------------------------------------------
  2. 26th January 1996
  3. -----------------------------------------------------------------------------
  4. Support Group Application Note
  5. Number: 293
  6. Issue: 0.11
  7. Author: DW
  8. -----------------------------------------------------------------------------
  9. CDFS Audio SWI Calls
  10. -----------------------------------------------------------------------------
  11. Notes: 
  12. This document details the publically releasable list of CDFS Audio SWI
  13. calls, which are valid for CDFS versions 2.21 through 2.28. Versions of CDFS
  14. later than 2.28 may not adhere strictly to the SWI interface described
  15. herein.
  16. -----------------------------------------------------------------------------
  17. Applicable Hardware: 
  18. All systems fitted with RISC OS 3.1 or later, running CDFS 2.21 or 2.28
  19.  
  20. Related Application Notes: 
  21. 273: CD ROM Drives and their Handling under RISC OS Explained
  22.  
  23. -----------------------------------------------------------------------------
  24. Copyright 1996 (C) Acorn Computers Limited 
  25.  
  26. Every effort has been made to ensure that the information in this leaflet is 
  27. true and correct at the time of printing. However, the products described in
  28. this leaflet are subject to continuous development and improvements and
  29. Acorn Computers Limited reserves the right to change its specifications at
  30. any time. Acorn Computers Limited cannot accept liability for any loss or
  31. damage arising from the use of any information or particulars in this
  32. leaflet. ACORN, ECONET and ARCHIMEDES are trademarks of Acorn Computers
  33. Limited.
  34. -----------------------------------------------------------------------------
  35. Support Group
  36. Acorn Computers Limited
  37. Acorn House
  38. Vision Park
  39. Histon
  40. Cambridge
  41. CB4 4AE                                                  
  42. -----------------------------------------------------------------------------
  43. Introduction
  44. ------------
  45. CDFS 2.21 is made up of three modules; the CDFS module itself, the
  46. CDFSDriver module and the CDFSFiler module. CDFS 2.28 comprises modified
  47. versions of CDFS, CDFSDriver and CDFSFiler, along with a number of
  48. demand-loading drivers designated CDFSSoft* tailored to particular models of
  49. CD ROM drive.
  50.   In general, the SWIs provided by these modules are reserved for internal
  51. use, and you must not use them in your own code, otherwise unpredictable
  52. results may occur. You should access files stored on CD ROMs using the same
  53. * commands and SWI calls with which you would access any other filing
  54. system; see the FileSwitch chapter of the RISC OS 3 Programmer's Reference
  55. Manual.
  56.  
  57. The SWI Calls
  58. -------------
  59. All CDFS audio SWIs conform to the RISC OS standard insofar as:
  60.  
  61. * Any registers not explicitly defined as result parameters are preserved
  62.  
  63. * The N, Z and C flags are preserved
  64.  
  65. * Errors are indicated by setting V and returning with R0 pointing at an
  66.   error block. If the bit 17 clear version is called, control passes to the
  67.   error handler instead.
  68.  
  69. * The SWI cannot be called from the background unless specifically documented
  70.  
  71. * All SWIs may be called from interrupt and event routines
  72.  
  73. but:
  74.  
  75. * No CDFSDriver SWIs preserve the interrupt state
  76.  
  77. * No CDFSDriver SWIs are re-entrant
  78.  
  79. CDFS SWI Calls
  80. --------------
  81. CDFS_ConvertDriveToDevice (SWI &41E80)
  82. Converts a logical drive number to a physical drive number
  83. On entry: 
  84.  R0 = logical drive number
  85. On exit: 
  86.  R0    preserved
  87.  R1 =  physical drive number
  88. Use: 
  89. This call converts a logical drive number to a physical drive number. You
  90. can then use the physical drive number to produce a CDFS control block,
  91. which you have to pass when calling CDFSDriver SWIs. For details of how to
  92. construct the block, see below.
  93.  
  94. This call returns an error if the logical drive is not known.
  95.  
  96. CDFSDriver SWI Calls
  97. --------------------
  98. CDFS Control Blocks
  99. Before you can access a CD ROM using any of the CDFSDriver SWIs, you need to
  100. set up a CDFS control block. When you call any of the SWIs, you pass a
  101. pointer to the block in R7.
  102.  
  103. A CDFS control block describes a physical device to the CDFS_Driver module,
  104. so it can use the correct routines. Consequently there must be one block for
  105. each CD ROM drive to be accessed. Once set up, the block remains valid until
  106. the next CDFS initialisation. CDFS may alter a block's contents, but you
  107. must not do so yourself, nor must you save a block and use it in another
  108. session.
  109.  
  110. Each CDFS control block is five words long. To construct a block, you must:
  111.  
  112. 1. Allocate memory for the block
  113.  
  114. 2. Call CDFS_ConvertDrivetoDevice to convert that drive's logical number to
  115.    a physical drive number
  116.  
  117. 3. Copy the returned physical drive number into the block as follows:
  118.  
  119. <Insert Fig1 here>
  120.  
  121. All bits of the control block not mentioned above must be initialised to
  122. zero. The whole process can be done as:
  123.  
  124. word0 = (drive_number AND 7)
  125. word1 = (drive_number AND &18)>>3
  126. word2 = (drive_number AND &E0)>>5
  127. word3 = (drive_number AND &FF00)>>8
  128. word4 = (drive_number AND &FFFF0000)>>16
  129.  
  130. Addressing Modes
  131. ----------------
  132. Locations on a CD are specified by one-word addresses. You can use three
  133. different addressing modes:
  134.  
  135.         Addressing mode        Meaning
  136.               0                Logical block addressing
  137.               1                Red Book addressing
  138.               2                Physical block addressing
  139.  
  140. Logical block addressing
  141. A logical block address gives an offset in blocks from the start of the CD's
  142. data area.
  143.  
  144. Red Book addressing
  145. A Red Book address gives a time offset from the CD's first frame, made up as
  146. follows from the MM:SS:FF location defined in the Red Book:
  147.  
  148.         Byte        Mnemonic        Meaning
  149.           0           FF        Frame number (0-74)
  150.           1           SS        Seconds (0-59)
  151.           2           MM        Minutes (0-99)
  152.           3                     Undefined
  153.  
  154. There are 75 frames per second.
  155.  
  156. Physical Block Addressing
  157. A physical block address gives an offset in blocks from the first block on
  158. the CD.
  159.  
  160. CD_OpenDrawer (SWI &41247)
  161. Stops the CD spinning, and opens the drawer / ejects the caddy
  162. On entry:
  163.  R7 = pointer to CDFS control block
  164. On exit:
  165.  R7 preserved
  166. Use:
  167. This call stops the CD spinning, opens the drawer and / or ejects the caddy.
  168. The call fails and returns an error if the drawer has previously been locked
  169. using CD_EjectButton or *Lock.
  170.  
  171. CD_EjectButton (SWI &41248)
  172. Enables or disables CD ejection.
  173. On entry:
  174.  R0 = 0 (to enable ejection) or 1 (to disable ejection)
  175.  R7 = pointer to CDFS control block
  176. On exit:
  177.  R0, R7 preserved
  178. Use: 
  179. This call enables or disables CD ejection. It is used by the *Lock command.
  180.  
  181. CD_EnquireAddress (SWI &41249)
  182. Returns the current address of the head.
  183. On entry:
  184.  R0 = addressing mode, for returned head location
  185.  R7 = pointer to CDFS control block
  186. On exit:
  187.  R0 = head address
  188.  R7 preserved
  189. Use:
  190. This call returns the current address of the head. You can use it while
  191. playing audio to determine which section of audio is playing.
  192.  
  193. CD_PlayAudio (SWI &4124B)
  194. Attempts to play a section of CD as audio, specified by address
  195. On entry:
  196.  R0 = addressing mode of parameters
  197.  R1 = start address of play section
  198.  R2 = end address of play section
  199.  R7 = pointer to CDFS control block
  200. On exit:
  201.  R0-R2, R7 preserved
  202. Use:
  203. This call attempts to play a section of CD as audio, specified by address.
  204. If the section contains non-audio information, the results are
  205. drive-dependent; you will not necessarily get an error returned, and some
  206. drives may still attempt to play the data. We therefore recommend you first
  207. use calls to CD_EnquireTrack to find out if the section you wish to play
  208. consists entirely of audio.
  209.  
  210. CD_PlayTrack (SWI &4124C)
  211. Attempts to play a section of a CD as audio, specified by track.
  212. On entry:
  213.  R0 = track number at which to start playing (1-99)
  214.  R1 = 255 to play to end of CD, or 254 to play to end of track
  215.  R7 = pointer to CDFS control block
  216. On exit:
  217.  R0, R1, R7 preserved
  218. Use:
  219. This call attempts to play a section of a CD as audio, specified by track.
  220. If the section contains non-audio information, an error is returned.
  221.  
  222. CD_AudioPause (SWI &4124D)
  223. Controls pausing of audio playing.
  224. On entry:
  225.  R0 = 0 to turn off pausing, if pause was in effect, or 1 to turn on pausing
  226.       if audio was playing
  227.  R7 = pointer to CDFS control block
  228. On exit:
  229.  R0, R7 preserved
  230. Use:
  231. This call controls pausing of audio playing.
  232.  
  233. CD_EnquireTrack (SWI &4124E)
  234. Returns the track range of a CD, or information on a specified track.
  235. On entry:
  236.  R0 = 0 to return track range, or a valid track number
  237.  R1 = pointer to 5 byte block
  238.  R7 = pointer to CDFS control block
  239. On exit:
  240.  R0, R1, R7 preserved
  241. Use:
  242. This call returns the track range of a CD, or information on a specified
  243. track. The information is returned in the block pointed to by R1.
  244.  
  245. If R0 = 0 on entry, the track range is returned in the block as follows:
  246.  
  247.         Byte        Contents
  248.           0        First track on CD (1-99)
  249.           1        Last ttrack on CD (1-99)
  250.          2-4        Corrupted
  251.  
  252. Track numbers do not necessarily start at 1.
  253.  
  254.  
  255. If R0 is a valid track number on entry, then information about that track is
  256. returned in the block:
  257.  
  258. Byte        Contents
  259. 0-3       Logical block address of track start (ie Mode 0 address)
  260.  4        Audio control bits specifying the type of information the track
  261.           holds:
  262.  
  263.           Bits        Meaning
  264.            0        0 indicates audio information, 1 indicates data
  265.                     information
  266.            1        0 indicates 4 channel sound, 1 indicates 2 channel sound
  267.           2-7        Reserved
  268.  
  269. CD_StopDisc (SWI &41252)
  270. Stops a CD playing.
  271. On entry:
  272.  R7 = pointer to CDFS control block
  273. On exit:
  274.  R7 preserved
  275. Use:
  276. This call stops a CD playing. You can use it to prematurely stop an audio
  277. play request.
  278.  
  279. CD_DiscUsed (SWI &41253)
  280. Returns the size of the CD currently in the drive.
  281. On entry:
  282.  R0 = addressing mode for returned size
  283.  R1 = pointer to 8 byte block
  284.  R7 = pointer to CDFS control block
  285. On exit:
  286.  R0 preserved
  287.  R1 corrupted
  288.  R7 preserved
  289. Use:
  290. This call returns the size of the CD currently in the drive. The call works
  291. with audio CDs as well as with CD ROMs. The size is returned in the block
  292. pointed to by R1 on entry.
  293.  
  294.         Bytes        Contents
  295.         0-3        Size of CD
  296.         4-7        Size of blocks on CD in bytes (usually 2048)
  297.  
  298. Note that R1 may be corrupted on exit.
  299.  
  300. CD_AudioStatus (SWI &41254)
  301. Returns the current audio status of the drive.
  302. On entry:
  303.  R7 = pointer to CDFS control block
  304. On exit:
  305.  R0 = audio status
  306.  R7 preserved
  307. Use:
  308. This call returns the current audio status of the drive, which may have one
  309. of the following values:
  310.         
  311.                  Value        Meaning
  312.                    0        Currently playing audio
  313.                    1        Currently paused
  314.                    2        Reserved (has no meaning at present)
  315.                    3        Audio play successfully completed
  316.                    4        Error occurred during last audio play
  317.                    5        Audio play has not been requested
  318.  
  319. To maintain drive independence, you should always treat values 3 and 5 in
  320. the same way.